CD Ware Multimedia 1995 May

home *** CD-ROM | disk | FTP | other *** search

/ CD Ware Multimedia 1995 May / cd Ware (Juegos) Epimundo.iso / DOS / C / BTRVEX.ZIP / BTRVEXPR.DOC < prev next >

Wrap

Text File | 1989-08-07 | 60.3 KB | 1,832 lines

The BTRV Express library manages the task of finding and opening Btrieve files. On the first call to any file, whether it is to retrieve a record or to find out how many records are in the file, the library will automatically allocate a position block and make sure that the correct position block is used in all subsequent calls to the file. In addition to the position block, the library will keep track of the memory location of the last record buffer used, the record length, the last index number used to access the file, and the length of each key definition. All of this information is updated each time you access a file. All references to a file are by file name. For instance, to get a record for Ed Edwards from a file named EMPLOYEE.DAT and read it into a buffer named EMP_BUF, the call would look like this: status = BGET(B_EQ,"EMPLOYEE.DAT",0,EMP_BUF,"ED EDWARDS") Even if this is the first call to the employee file in your program, the record will be retrieved. You never have to explicitly OPEN the file. The library routines will find your file if it is in the DOS search path. These routines also free you from hard coding the record lengths of your data files. Just change the structure definition of the record buffer in your application and the library will automatically adapt to the new record length by inspecting the data file. All calls to Btrieve are made through a central module. The advantage of this is that you can modify that module to perform a certain function each time a file is accessed. This feature could be most most useful in a network environment. For instance, you can place a routine in the central module that checks for hardware errors on the server and logs the user off gently if there is trouble. Most errors are handled automatically, which will drastically reduce the amount of error handling code you need to write. If a file is not found when a record is requested, an error message will display and the program will exit to DOS. Usually, the control will only be passed back to your program if the call is successful. Under some circumstances, you will still need error handling code. One example is record searching. If a record is not found (but the filename is valid), a return code will give the status of the search. Another example is adding a record. If a duplicate record is added on a key defined as not allowing duplicates, an error code will be returned to your application. Requirements This library was designed for Microsoft C version 5.0 and above, Btrieve version 4.10, an IBM PC, AT, PS/2 or 100% compatible. It is intended for use with a hard disk but this is not required. A version for Turbo C v2.0 is planned. Also in the works is a Norton Guide reference file. Page 2 BTRV Express How It Works Before making any other library call, one of the first statements in your application must be a call to BSTART(). This module does two things: it makes sure that the Btrieve record manager is loaded in memory and locates the BTRERROR.DAT file which stores the library's error messages. If either Btrieve is not loaded or BTRERROR.DAT cannot be found, the program will exit to DOS. If control is returned to your application, then you may make library calls as usual. The BSTART() module will also load the current version of Btrieve in a global variable named BTR_VERSION. A global array named BTR_FILES holds the definitions for open files. It is maintained by the central calling module BXTR. Each time a request comes through BXTR, the filename is searched for in BTR_FILES. If the file name is found, the library will supply all of the needed information to make the Btrieve call. If the file name is not found, a new position block is allocated and the file is opened, after which the file's structure and related information (record buffer, index number, record length, etc.) are entered into the array. The call to Btrieve is then processed. An invalid filename will always cause the library to display a message and exit to DOS. This error will be caught and processed in the BXTR module. Other errors are caught in the individual routines that handle special calls and cases. These are documented in the function call reference and in the source code. After a call involving record retrieval, addition, or update, the 'keytemp' character buffer contains the key value for the record. For example, if you add a record to an employee file that is indexed on employee number, the 'keytemp' buffer will contain the employee number. This buffer is quite handy for GET KEY ONLY operations (see Btrieve manual for a better explanation). The 'keytemp' buffer is used mainly as a holding area for search criteria. If you were to search a file for a certain employee number, the number would be copied to 'keytemp'. The address of 'keytemp' is passed to Btrieve so that the returned key can be placed in the buffer and the original key value is preserved. The 'keytemp' buffer can also be loaded directly by your application for use in GET operations but remember that its value is not guaranteed to be the same upon return from the call. If it is important to retain the original value, then pass the key in your own separate buffer. Page 3 BTRV Express Using the Library in Your Application The source code is written for Microsoft C v5.0. Include the following line at the top of your application: #include <BTRVEXP.H> Compile your application (the /Zp switch is recommended) and link it with the correct model version of BTRV Express: BTRVEXPS.OBJ - Small Model BTRVEXPC.OBJ - Compact Model BTRVEXPM.OBJ - Medium Model BTRVEXPL.OBJ - Large Model Global Variables int BSTATUS: Always holds the status value of the last Btrieve call. int open_files: Number of currently open Btrieve files. struct BTR_FILES btr_files[MAX_BTR_FILES] Main array which holds position blocks and support information for file management. This array is manipulated by the BXTR routine. struct { char *filename; char *pos_blk; char *last_rec_buf; char *ndx_lens; int numindexes; int rec_len; int last_index; } btr_files[MAX_BTR_FILES]; filename : name of file (filename and extension only). pos_blk : allocated 128 byte position block. last_rec_buf: address of last record buffer used on this file. ndx_lens : pointer to integer array of index lengths (one value for each index). numindexes : number of indexes (number of elements in ndx_lens). rec_len : record length. last_index : last index number used to access a record. char keytemp[255]: Temporary buffer for working with key values. After a BGET call, it will hold the key value of record retrieved. Since a key definition cannot be longer than 255 bytes, keytemp will hold any value. Page 4 BTRV Express struct BTR_VERSION btr_version: Holds version of Btrieve being used. See documentation for function BSTART() for structure. struct STATBUF global_statbuf: Global status buffer used when calling BFILEINFO. The status buffer is large enough to hold any file definition containing the maximum of 24 key segment definitions and an alternate collating sequence. If you use this buffer to create your own files and want to load an alternate collating sequence, remember that the definition for the collating sequence must immediately follow your last key segment definition. The Alternate Collating Sequence will usually not be placed in 'global_statbuf.altcolseq'. The slot is there just to reserve enough space for the longest possible definition. The length of the file definition is passed back and forth through 'global_statbuf.buf_len'. struct ERROR_MSG errmsg: The records in the file BTRERROR.DAT correspond to the Btrieve error codes. When a library function returns a status other than 0, you can call GET_ERR_MSG with the status number. The error message is returned in the global variable 'errmsg'. For the structure and an example of its use, see the explanation of the GET_ERR_MSG function call. int CATCH_ERROR; CATCH_ERROR is initialized to TRUE. When TRUE, fatal errors that are caught by the library will cause an error message to display at the bottom of the screen and an exit to DOS. If you wish to have your own error handling system, initialize this variable to FALSE and all errors will be returned to your program in the status code (BSTATUS). int RETURN_KEY_BUFFER When TRUE, a call made to retrieve a record returns the key value in your defined key buffer. This means, for example, that to search for an employee by a partial name, you must pass a key buffer long enough to hold the entire name. This is not always convenient. For that reason, a temporary buffer (see 'keytemp' above) has been reserved to catch the key value of any record when it is retrieved. The RETURN_KEY_BUFFER variable is initialized to FALSE. The key buffer you pass down will remain unaltered unless you change the value of RETURN_KEY_BUFFER to TRUE. Btrieve will then return the key value both in your key buffer and in 'keytemp'. You can set the value of RETURN_KEY_BUFFER at any time in your application. int DEL_POSITION Positiong the data file after a DELETE poses a special problem. Under normal circumstances, the data file is at an invalid position after a DELETE. This means that many of the library functions will not work if called directly after a deletion. The external variable DEL_POSITION tells the library what to do after a record deletion. If TRUE (the default setting), then the library will place the data file at the record directly after the deleted one using the current index number. If you have just deleted the highest record in the index, the file will be positioned at the next highest record. You Page 5 BTRV Express should note that the act of positioning the file will alter the contents of that file's record buffer even though you do not pass the buffer as a parameter to BDELETE. If DEL_POSITION is FALSE, then only the deletion happens during a BDELETE call and the file is not positioned afterward. It is up to your application to determine the next correct position. Note: keytemp, global_statbuf and charbuf are used by the library as temporary holding areas for various items. They are not guaranteed to retain values across calls. Defined Constants #define TRUE 1 #define FALSE 0 #define ALL_FILES NULL ; See BCLOSE for usage #define B_LOCK_WAIT 100 ; See BGET for usage #define B_LOCK_NOWAIT 200 ; See BGET for usage #define B_OPEN 0 #define B_CLOSE 1 #define B_INSERT 2 #define B_UPDATE 3 #define B_DELETE 4 #define B_EQ 5 ; Get Equal #define B_NEXT 6 ; Get Next #define B_PREV 7 ; Get Previous #define B_GT 8 ; Get Greater Than #define B_GE 9 ; Get Greater Than or Equal to #define B_LT 10 ; Get Less Than #define B_LE 11 ; Get Less Than or Equal to #define B_LOW 12 ; Get Lowest #define B_HIGH 13 ; Get Highest #define B_CREATE 14 #define B_STAT 15 #define B_EXTEND 16 #define B_SETDIR 17 #define B_GETDIR 18 #define B_BEGTRANS 19 #define B_ENDTRANS 20 #define B_ABORTTRANS 21 #define B_GETPOS 22 #define B_GETDIRECT 23 #define B_STEP 24 #define B_STOP 25 #define B_VERSION 26 #define B_UNLOCK 27 #define B_RESET 28 #define B_SETOWNER 29 #define B_CLEAROWNER 30 #define B_EQ_KEY 55 ; Key only operation #define B_NEXT_KEY 56 ; Key only operation Page 6 BTRV Express #define B_PREV_KEY 57 ; Key only operation #define B_GT_KEY 58 ; Key only operation #define B_GE_KEY 59 ; Key only operation #define B_LT_KEY 60 ; Key only operation #define B_LE_KEY 61 ; Key only operation #define B_LOW_KEY 62 ; Key only operation #define B_HIGH_KEY 63 ; Key only operation And if you like to use lower case: #define b_open B_OPEN #define b_close B_CLOSE #define b_insert B_INSERT #define b_update B_UPDATE #define b_delete B_DELETE #define b_eq B_EQ #define b_next B_NEXT #define b_prev B_PREV #define b_gt B_GT #define b_ge B_GE #define b_lt B_LT #define b_le B_LE #define b_low B_LOW #define b_high B_HIGH #define b_create B_CREATE #define b_stat B_STAT #define b_extend B_EXTEND #define b_setdir B_SETDIR #define b_getdir B_GETDIR #define b_begtrans B_BEGTRANS #define b_endtrans B_ENDTRANS #define b_aborttrans B_ABORTTRANS #define b_getpos B_GETPOS #define b_getdirect B_GETDIRECT #define b_step B_STEP #define b_stop B_STOP #define b_version B_VERSION #define b_unlock B_UNLOCK #define b_reset B_RESET #define b_setowner B_SETOWNER #define b_clearowner B_CLEAROWNER #define b_eq_key B_EQ_KEY #define b_next_key B_NEXT_KEY #define b_prev_key B_PREV_KEY #define b_gt_key B_GT_KEY #define b_ge_key B_GE_KEY #define b_lt_key B_LT_KEY #define b_le_key B_LE_KEY #define b_low_key B_LOW_KEY #define b_high_key B_HIGH_KEY Page 7 BTRV Express Error Return Codes #define ERR_INVALOP 1 #define ERR_IO 2 #define ERR_NOOPEN 3 #define ERR_KEYNOTFOUND 4 #define ERR_DUPLICATE 5 #define ERR_INVALKEYNUM 6 #define ERR_DIFFKEYNUM 7 #define ERR_INVALPOSITION 8 #define ERR_EOF 9 #define ERR_MODIFIABLE 10 #define ERR_INVALFILENAME 11 #define ERR_FILENOTFOUND 12 #define ERR_EXTENSION 13 #define ERR_PREOPEN 14 #define ERR_PREIMAGE 15 #define ERR_EXPANSION 16 #define ERR_CLOSE 17 #define ERR_DISKFULL 18 #define ERR_UNRECOVERABLE 19 #define ERR_NORECMANAGER 20 #define ERR_KEYBUFLEN 21 #define ERR_RECBUFLEN 22 #define ERR_POSBLOCK 23 #define ERR_PAGESIZE 24 #define ERR_CREATEIO 25 #define ERR_NUMKEYS 26 #define ERR_KEYPOS 27 #define ERR_RECLEN 28 #define ERR_KEYLEN 29 #define ERR_NOTBTRFILE 30 #define ERR_EXTEND 31 #define ERR_EXTENDIO 32 #define ERR_EXTENDNAME 34 #define ERR_DIRECTORY 35 #define ERR_TRANSACTION 36 #define ERR_BEGTRANS 37 #define ERR_TRANSCONTROL 38 #define ERR_ENDABORT 39 #define ERR_TRANSACTMAX 40 #define ERR_TRANSOPENCLOS 41 #define ERR_ACCELACCESS 42 #define ERR_INVALRECADD 43 #define ERR_NULLKEYPATH 44 #define ERR_KEYFLAGS 45 #define ERR_ACCESSDENIED 46 #define ERR_MAXOPENFILES 47 #define ERR_ALTCOLSEQ 48 #define ERR_KEYTYPE 49 #define ERR_OWNERSET 50 #define ERR_INVALIDOWNER 51 #define ERR_WRITINGCAHCE 52 #define ERR_INVINTERFACE 53 Page 8 BTRV Express #define ERR_CONFLICT 80 #define ERR_LOCKFULL 81 #define ERR_LOSTPOSITION 82 #define ERR_OUTSIDETRANS 83 #define ERR_RECORDINUSE 84 #define ERR_FILEINUSE 85 #define ERR_FILEFULL 86 #define ERR_HANDLEFULL 87 #define ERR_MODE 88 #define ERR_NAME 89 #define ERR_DEVICEFULL 90 #define ERR_SERVER 91 #define ERR_TRANSFULL 92 #define ERR_DEMO24 99 Constants used in calls to BFILEINFO #define NUM_RECS 1 #define REC_LEN 2 #define PG_SIZE 3 #define INDEXES 4 #define FLAGS 5 #define ALL 6 File Definition Structures (used in BFILEINFO) typedef struct { int key_pos; int key_len; int key_flags; long num_keys; unsigned char ext_key_type; unsigned char null_value; char reserved[4]; } BTRSEGMENT; typedef struct { int reclen; int pgsize; int numind; long numrecs; int fileflags; char res[4]; BTRSEGMENT segment[24]; char altcolseq[264]; int buf_len; } STATBUF; Page 9 BTRV Express General Structures struct BTR_FILES { char *file_name; char *pos_blk; char *last_rec_buf; int rec_len; int last_index; } btr_files[15]; typedef struct { int btr_major; int btr_minor; char net; int lib_major; int lib_minor; } BTR_VERSION; Function Prototypes int BADD(char *,char *) ..........................................ADD a record int BCHANGEINDEX(char *,int) ......................Change current index Number int BCLEAROWNER(char *) ......................................Clear File Owner int BCLOSE(char *) .....................................CLOSE one or all files int BCREATE(char *, STATBUF *) ..............................CREATE a new file int BDELETE(char *) .....................................DELETE current record int BFILEINFO(char *,int,void *) .........................Get File Information int BGET(int,char *,int,char *,char *) .............................Get Record int BGETDIRECT(char *,void *,char *) .................Get Record by Position # int BGETDIRECTORY(int,char *) ...........................Get Current Directory int BGETPOSITION(char *,void *) ..............Get Position # of Current Record int BSETDIRECTORY(char *) ...............................Set Current Directory int BSETOWNER(char *,char *,int)................................Set File Owner int BSTART(void) ...........................................Initialize Library void BTR_ERROR(int, char *) .....................Display Error Message and Exit int BTRANS(int) ...........................................Manage Transactions int BTRV(int,char *,void *,int *,char *,int) ................BTRIEVE INTERFACE int BUNLOCK(char *) ....................................Unlock Records in File int BUPDATE(char *,void *) ..............................Update Current Record int BXTR(int,char *,int,char *,char *) .................Central Calling Module int BZAP(char *) ...................................Delete All Records in File int GET_FILE_NUM(char *) .......................Get Index into BTR_FILES Array int GET_ERR_MSG(int).......................Return Description of Btrieve Error The following pages describe each function individually. Page 10 BTRV Express int BADD(char *filename, char *record_buf) What it does: Use this function to add new records to your data files. Parameters: char *filename: File name. char *record_buf: Record to add. Returns: Status of Btrieve Call - or - Exits program if file not found Example: Add a new employee record to a file. struct { char Name[30]; char Address[40]; unsigned long Emp_Num; } Employee; int status; strcpy(Employee.Name,"Leonard Bernstein"); strcpy(Employee.Address,"Philharmonic Hall"); Employee.Number = 5768L; status = BADD("EMPLOYEE.DAT",&Employee); if (status == ERR_DUPLICATE) printf("That number already exists"); Notes: BADD will return a status code under all circumstances except when the requested file does not exist. Your application must have code to decide what to do in the event of an error. Page 11 BTRV Express int BCHANGEINDEX(char *filename, int index) What it does: Use this function to change the current index of a file without seeking another record. Btrieve will not normally let you search for a record using one index and go to the next record using another index. The function is called automatically by BGET if you request a different index than the last one you used. Therefore, you will generally not need to use this function. Parameters: char *filename: File name. int index: New key number to use when stepping through file. Returns: 0 if successful. ERR_INVALKEYNUM (6) if key does not exist. Exits program if file not found. Example: Search for an Employee by number (key 0) and then list the next three in alphabetical order (key 1). struct { char Name[30]; char Address[40]; unsigned long Emp_Num; } Employee; int status,i; unsigned long Emp_Number; Emp_Number = 34215L; status = BGET(B_GE,"EMPLOYEE.DAT",0,Employee,&Emp_Number); status = BCHANGEINDEX("EMPLOYEE.DAT",1); for (i=0 ; i<3 && status == 0; i++) { printf("%s\n",Employee.Name); status = BGET(B_NEXT,"EMPLOYEE.DAT",1,Employee,keytemp); } Notes: Remember that in the above example, the BCHANGEINDEX call is not really needed. The BGET NEXT call will automatically call BCHANGEINDEX if it detects the change. Page 12 BTRV Express int BCLEAROWNER(char *filename) What it does: Clears ownership of a file. Removes need to identify owner each time the file is opened. Parameters: char *filename: Name of file to remove ownership. Returns: 0 if successful. Exit to DOS if bad file name. Example: status = BCLEAROWNER("EMPLOYEE.DAT"); Notes: The file must be properly opened with correct ownership before making this call. Page 13 BTRV Express int BCLOSE(char *filename) What it does: If BCLOSE is called with a filename, then that file will be closed. The position block will be deallocated and the entry in the 'btr_files' array will be deleted. If BCLOSE is called with ALL_FILES (a macro defined as NULL), then a Btrieve RESET will occur, all files will be closed and the entire 'btr_files' array will be cleared. Parameters: char *filename = Name of file to close or ALL_FILES. Returns: Btrieve Status code of the close. Example: Close all files before exiting your application. status = BCLOSE(ALL_FILES); Notes: None. Page 14 BTRV Express int BCREATE(char *filename, STATBUF *statbuf) What it does: BCREATE will create a new file based on your specifications. The function can be used in a number of ways. It is called by BZAP, a routine that deletes all records in a file. BZAP performs a BFILEINFO on the file which loads its definition into 'global_statbuf'. The status buffer is then passed to BCREATE along with the original filename to create a new blank file. Another use for BCREATE and BFILEINFO is to copy just the structure of a file. Use BFILEINFO to load the 'global_statbuf' and call BCREATE with a new file name. The length of the file definition must be passed in STATBUF.buf_len. See the Btrieve manual for information on how to assemble your own status buffer to create new files. Parameters: char *filename: Name of file to create (path can be included). STATBUF *statbuf: Pointer to valid Btrieve status (file definition) buffer. Returns: Status of Btrieve operation. You must decide what to do on error. Example: Create a temporary file with the same structure as your employee file. int status; status = BFILEINFO("EMPLOYEE.DAT",ALL); status = BCREATE("EMPTEMP.DAT",&global_statbuf); Notes: None. Page 15 BTRV Express int BDELETE(char *filename) What it does: Deletes the current record from the file. After deletion, the file will be placed at the next record according to the current index. If you have just deleted the highest record on the index, the file will point to the next highest record. If the global variable 'DEL_POSITION' is FALSE, no position will be established after the delete call. Your application must set the file's position. Parameters: char *filename: Name of file. Returns: 0 if successful. ERR_EOF (9) if there are no more records in the file. Program will exit if the filename is invalid. Example: Delete all of the Robinsons from the Employee file. Use global variable BSTATUS to determine error conditions. struct { char Name[30]; char Address[40]; unsigned long Emp_Num; } Employee; int status; BGET(B_GE,"EMPLOYEE.DAT",0,Employee,"Robinson"); while (BSTATUS == 0 && strncmp("Robinson",Employee.Name,8) == 0) BDELETE("EMPLOYEE.DAT"); Notes: Note that a BGET NEXT call is not needed to find the next employee. Page 16 BTRV Express int BFILEINFO(char *filename, int type, void *parm) What it does: BFILEINFO will first get the file's position, call a Btrieve STAT operation, load the parameter to pass back, and restore the file's position with a BGETDIRECT. The STAT loads the 'global_statbuf' with the file's information. The 'type' parameter lets the routine choose which piece to send back. Parameters: char *filename: Name of file. int type: Type of information requested. Possible values are: NUM_RECS - number of records REC_LEN - record length INDEXES - number of indexes PG_SIZE - page size FLAGS - Btrieve file flags (See Btrieve documentation) ALL - Load global_statbuf void *parm: Pointer to returned information. 'parm' must point an integer if 'type' is REC_LEN, INDEXES, PG_SIZE, or FLAGS. 'parm' must point to an unsigned long integer if 'type is NUM_RECS. If the type is 'ALL', you can pass NULL for the parameter 'parm'. The file's structure will be passed back in global_statbuf. Otherwise, you must pass a pointer to a STATBUF structure. Example: Find out how many Employees there are in the file. unsigned long NUM_EMPS; status = BFILEINFO("EMPLOYEE.DAT",NUM_RECS,&NUM_EMPS); printf("There are %lu Employees Here",NUM_EMPS); Returns: 0 if successful. Otherwise, it will return the status of the GETPOSITION call at the end of the routine. Notes: None. Page 17 BTRV Express int BGET (int get_type, char *filename, int index, char *rec_buf, char *key_buf) What it does: BGET is the main procedure used to access the records in your file. Tell it the file name, index, what kind of search, and where to put the answer to your query. Record Locking is accomplished by adding a locking constant to the get_type. Locking constants are: B_LOCK_WAIT : Record lock with waiting. B_LOCK_NOWAIT: Record lock without waiting. Parameters: int get_type: Type of search. Possible values: These values return entire records: B_EQ - get equal to B_GT - get greater than B_GE - get greater than or equal to B_LT - get less than B_LE - get less than or equal to B_LOW - get lowest B_HIGH - get highest B_NEXT - get next in order B_PREV - get previous in order These values return keys only (see Btrieve manual for explanation): B_EQ_KEY - get equal to B_GT_KEY - get greater than B_GE_KEY - get greater than or equal to B_LT_KEY - get less than B_LE_KEY - get less than or equal to B_LOW_KEY - get lowest B_HIGH_KEY - get highest B_NEXT_KEY - get next in order B_PREV_KEY - get previous in order char *filename: File name. int index: Index number to use for search. A value of -1 will cause the library to use the last known index number for the file. Page 18 BTRV Express char *rec_buf: Record buffer address. Passing a NULL value here will tell the library to use the last known record buffer. char *key_buf: buffer of key to search for. You can pass 'keytemp' or NULL in this parameter if you wish (both have the same effect). Returns: Status of Btrieve call. Program will exit if the file does not exist. Example: Print all of your employee's names. struct { char Name[30]; char Address[40]; unsigned long Emp_Num; } Employee; int status; status = BGET(B_LOW,"EMPLOYEE.DAT",0,&Employee,keytemp); while (status == 0) { printf("%s\n",Employee.Name); status = BGET(B_NEXT,"EMPLOYEE.DAT",0,&Employee,keytemp); } Example call with wait lock: BGET(B_LOW+B_LOCK_WAIT,"EMPLOYEE.DAT",0,&Employee,keytemp); For a full example with record locking see BUPDATE(). Notes: After every call to BGET, the 'keytemp' buffer holds the complete key value of the record just retrieved. For instance, suppose that your employee file has a key consisting of Employee Number concatenated with the Employee Name. A call to retrieve the record by just the employee number will load 'keytemp' with the full key (Number and Name). You can use that value as needed, but remember that this buffer is subject to change during the next library call. If RETURN_KEY_BUFFER is set TRUE or if you have requested a key-only retrieval, make sure that you have enough room in your defined key buffer for the returned value. Page 19 BTRV Express int BGETDIRECT(char *filename, void *position, char *rec_buf) What it does: Positions a file based on a 4-byte position number. Parameters: char *filename: File name. void *position: Pointer to 4-byte position buffer. char *rec_buf: Pointer to record buffer. If rec_buf is NULL, then BXTR will use the last known record buffer location. Returns: Status of Btrieve call. Program will exit if file is not found. Example: Position the file based on an external index. struct { char SSN[11]; unsigned long pos; } EXT_KEY; struct { char Name[30]; char Address[40]; unsigned long Emp_Num; } Employee; int status; unsigned long EMP_NUMBER; status = BGET(B_EQ,"EXTRAKEY.NDX",0,&EXT_KEY,&EMP_NUMBER); if (status == 0) status = BGETDIRECT("EMPLOYEE.DAT",&EXT_KEY.pos,&Employee); Notes: None. Page 20 BTRV Express int BGETDIRECTORY(int drive,char *path) What it does: Returns the current directory of the requested drive. Parameters: int drive: 0 = use default drive 1 = Drive A 2 = Drive B 3 = Drive C etc. char *path: buffer to receive directory. This buffer must be at least 64 bytes long. Returns: STATUS of Btrieve call. Example: Report directory of current drive. char path[64]; status = BGETDIRECTORY(0,path); printf("%s",path); Notes: None. Page 21 BTRV Express int BGETPOSITION(char *filename,void *pos) What it does: Gets the 4-byte Btrieve position of the record in the named file. This value is to be used at some later time by a BGETDIRECT call. Parameters: char *filename: File name. void *pos: Pointer to 4-byte position buffer. Returns: Status of Btrieve call. Program will exit if file is not found. Example: long pos; status = BGETPOSITION("EMPLOYEE.DAT",&pos); See Btrieve documentation examples for use of this call. Notes: None. Page 22 BTRV Express int BSETDIRECTORY(char *path) What it does: Sets the current directory on any drive. If the path name does not include a drive specification, the default drive is assumed. Parameters: char *path: Pathname to set. Example: Change to the "\BTRIEVE" directory on the current drive. status = BSETDIRECTORY("\\BTRIEVE"); Returns: 0 if successful. Exit to DOS if error occurs. Notes: This function works exactly like the DOS "CHDIR" command. - If the first character of 'path' is not a backslash, the path is appended to the current directory. - If a drive specification is given in 'path', it sets the current directory on that drive but does not effect your default drive status. For example if you are currently on drive C and call this function with path = "D:\APPLIC", your default drive will still be C. Your application must specifically change drives to access D. Page 23 BTRV Express int BSETOWNER(char *filename,char *owner,int mode) What it does: Establishes ownership of a Btrieve file. Once a file has been assigned an owner, the owner's name must be passed in the record buffer when the file is opened. If the name is not present, the file cannot be used. Parameters: char *filename: Name of file. char *owner: Owner name. ASCIIZ string of up to eight characters. int mode: 0 - Requires owner ID for any access; no data encryption 1 - Permit read-only access without owner ID; no data encryption 2 - Requires owner ID for any access; data encryption 3 - Permit read-only access without owner ID; data encryption Example: Set an owner for a file, permit read-only access with no ID, do not encrypt data. status = BSETOWNER("employee.dat","TWIT",0); Returns: 0 if successful. Exit to DOS if error occurs. Notes: Once ownership has been set, the owner ID must be present in the record buffer whenever the file is subsequently opened. It is suggested that for those files with ownership, you use a UNION structure with your defined record buffer to make life easier. See the example on the following page. union { struct { char EMP_NUM[5]; char EMP_NAME[20]; } record char owner[9]; } EMP_BUF; strcpy(EMP_BUF.owner,"TWIT"); BGET(B_LOW,"employee.dat",0,&EMP_BUF.record,keytemp); Page 24 BTRV Express After the first call to the file, assuming it is successful, you do not need the owner ID in the record buffer. If you forget the owner ID, there is no way to recall it from the file. Page 25 BTRV Express int BSTART() What it does: Makes sure that Btrieve is loaded in memory and locates file which contains the error messages. The first thing this module does is try and load the version of Btrieve into the the global variable, BTR_VERSION. This variable's structure is: struct { int btr_major; int btr_minor; char net; int lib_major; int lib_minor; } BTR_VERSION; If this call fails, then Btrieve is not loaded in memory and the library will print an appropriate message and exit to DOS. If the call is successful, then the version of Btrieve as well as the version number of this library are available to your application. The second thing this module does is search for the file BTRERROR.DAT. If this file is not in the current directory or current DOS search path, then the library cannot print its standard error messages. A predefined error message will print and the library will exit to DOS. If you do not plan to use the predefined error messages and do not want the library to search for BTRERROR.DAT, set CATCH_ERROR to FALSE before calling BSTART(). If the version is loaded correctly and the error file is found, then control is returned to your application. Returns: 0 if successful. Exits to DOS if error occurs. Example: status = BSTART(); Notes: None. Page 26 BTRV Express void BTR_ERROR(int op, char *message) What it does: Go to the bottom of the screen, display the operation code, status of last Btrieve call (held in global variable BSTATUS), and an error message before exiting back to DOS. This routine is called when the library catches a critical error. The error message can be supplied in one of two ways. If BSTATUS is not equal to zero, this function will search for BSTATUS in a special file called BTRERROR.DAT. The message which to corresponds to that error number will be displayed. If you wish to supply your own error message, set BSTATUS to 0 and pass the message instead of a filename for the second parameter. After the message is displayed, a Btrieve RESET function is called (unless the error number is 20) and the program will exit out to DOS. Parameters: int op: Operation being performed when error occurred. char *message: Pointer to error message. Returns: No return code. Program exits to DOS. Example: Check for duplicate employee numbers when entering a record. Exit to DOS if a duplicate is found. Use global variable BSTATUS to check for error. int status; struct { char Name[30]; char Address[40]; unsigned long Emp_Num; } Employee; strcpy(Employee.Name,"James Taylor"); strcpy(Employee.Address,"111 Fire and Rain Lane"); Employee.Emp_Num = 5555L; BADD("EMPLOYEE.DAT",&Employee); if (BSTATUS == ERR_DUPLICATE) BTR_ERROR(B_ADD,"EMPLOYEE.DAT"); Notes: None. Page 27 BTRV Express int BTRANS(int transtype) What it does: Calls Btrieve and tells it to Begin, End or Abort transaction. Also sets global variable TRANS_IN_PROGRESS to TRUE or FALSE. Parameters: int transtype: B_BEGTRANS - Begin Transaction ; TRANS_IN_PROGRESS = TRUE B_ENDTRANS - End Transaction ; TRANS_IN_PROGRESS = FALSE B_ABORTTRANS - Abort Transaction ; TRANS_IN_PROGRESS = FALSE Returns: 0 if successful. Program will exit to DOS if an incorrect parameter is passed or the Btrieve call produces an error. Example: int status; status = BTRANS(B_BEGTRANS); . . . calls adding or updating records; . . if (status != 0) status = BTRANS(B_ABORTTRANS); else status = BTRANS(B_ENDTRANS); Notes: Beginning a transaction involves no writing to files. Ending a transaction gives the user no control over file writes. Because of this, the call to Btrieve is made directly from this routine and not through BXTR. Page 28 BTRV Express int BTRV (int op, char *position_block, char *record_buffer, int *record_length, char *key_buffer, int index) What it does: Standard interface call to Btrieve. Notes: See Btrieve Manual. Page 29 BTRV Express int BUNLOCK(char *filename) What it does: Unlocks all records in the named file. Parameters: char *filename: Name of file to unlock. Returns: 0 if successful. Exit to DOS if error occurs. Example: status = BUNLOCK("employee.dat"); Notes: None. Page 30 BTRV Express int BUPDATE(char *filename, void *rec_buf) What it does: Updates the current record with the information in rec_buf. Because an update sometimes does not position the file correctly, the library gets the 4-byte position number of the current record before the call and does a BGETDIRECT after the call. This ensures that the file is correctly positioned. Parameters: char *filename: File name. char *rec_buf: Pointer to record buffer. Returns: If the UPDATE call to Btrieve fails, the return code is the Btrieve error code. Otherwise, the return code is the result of the final BGETPOSITION call. Program will exit to DOS if file is not found. Example: Change an employee's address. Lock the record while editing. struct { char Name[30]; char Address[40]; unsigned long Emp_Num; } Employee; BGET(B_EQ+B_LOCK_WAIT,"EMPLOYEE.DAT",0,&Employee,"Willard, Fred"); if (BSTATUS == 0) { strcpy(Employee.Address,"10 Madison Ave"); BUPDATE("EMPLOYEE.DAT",&Employee); BUNLOCK("EMPLOYEE.DAT"); } Notes: Since all library calls position the file at some record, the only times an update should fail are: - The file name is invalid. - There are no records in the file. - There is some hardware error. Page 31 BTRV Express int BXTR (int op, char *filename, int index, char *record_buffer, char *key_buffer) What it does: This is the module through which the library make almost all calls to Btrieve. It manages the 'btr_files' array, allocates position blocks, makes sure that there are proper buffers for all activities, and catches some fundamental program errors such as bad file names or too many open files. Some of the parameters can be supplied through defaults stored in the btr_files array. If the index parameter is passed as -1, BXTR will use the last known index number. The 'rec_buf' pointer has a similar default mode. If the pointer is NULL, BXTR will use the last_rec_buf (stored in the 'btr_files' array) for that file. If the key_buf parameter is NULL, keytemp is used. Under some conditions, there is no support information for the file. For instance, if the first call to a file is through BFILEINFO, then no previous record buffer exists. In cases like this, a temporary record buffer will be allocated, used for the call, and freed afterward. In other cases, a dummy position block is allocated as well. BXTR will also manage the shuffling around of the 4-byte position buffer during BGETPOSITION and BGETDIRECT calls. This ensures that a BGETPOSITION call works correctly but the first four characters of the record buffer are properly restored afterward. You should not have to call this function directly for normal processing. However, if you are brave enough to modify source code, you can put your own routines in here. One idea for added functionality would be to use some kind of signal detecting code just before the actual BTRV call. The code could see if a system administrator would like all users to log off of the network. The routine would detect the signal, log the users off and change the default drive to the local hard disk. This saves you the hassle of writing code for special logoff procedures or error detecting procedures every time you request a record. Because virtually all I/O is directed through this module, you can just write the code once. Parameters: int op: Btrieve Operation number. There are macro definitions for these numbers. See BTRVDEFS.H. char *filename: File name. int index: Index number to use for record retrieval. If index = -1, then the library will use the last known index number which is stored in the BTR_FILES array. If there is no last known index, the library will supply a value of 0. Page 32 BTRV Express char *record_buffer: Pointer to record buffer. If this pointer is NULL, the library will use the last known record buffer pointer. Under special circumstances when there is no last known pointer, a temporary buffer will be allocated for the call and freed before returning. char *key_buffer: Pointer to key buffer. If the call is for a record retrieval, the key buffer is unaltered by the call. The key of the returned record is returned in the global buffer 'keytemp'. If the call is a KEY operation (i.e., GET KEY), the key value is returned in the buffer that is passed. If key_buffer is passed as NULL, the library will supply the pointer to 'keytemp' to the Btrieve call. Example: This function is called by almost every module in the library. Examine the source code for examples of its usage. Notes: None. Page 33 BTRV Express int BZAP(char *filename) What it does: Deletes all records in a file. Whereas the Btrieve delete function does not reclaim the space used by a record, this function will reclaim it all. It creates an empty copy of the file using the same filename. Parameters: char *filename: Name of file to zap. Returns: Status of BCREATE call. Example: status = BZAP("EMPLOYEE.DAT"); Notes: The function uses 'global_statbuf' to hold the file's definition. Page 34 BTRV Express int GET_ERR_MSG(int errnum) What it does: Returns a 40-character description of a Btrieve error code through the global variable 'errmsg'. Parameters: int errnum: The status of the last library function call. global variable 'errmsg': struct ERROR_MSG { int errnum; char descrip[40]; } errmsg; Returns: If the error code is found in BTRERROR.DAT, the function returns 0 and places the message and error number in global variable 'errmsg'. Otherwise, returns the status of the record search. Example: An error occurs while adding a record. Print the error message. extern ERROR_MSG errmsg; main() { int status; char record[100]; . . . status = BADD("employee.dat",&record); if (status != 0) { GET_ERR_MSG(status); printf("%.40s\n",errmsg.descrip); } . . . } Notes: If you set CATCH_ERROR to FALSE before running BSTART(), then it is possible that the file BTRERROR.DAT is unavailable. Page 35 BTRV Express int GET_FILE_NUM(char *filename) What it does: Returns the index into the 'btr_files' array of the file. Parameters: char *filename: File name. Returns: Number between 0 and MAX_BTR_FILES if successful or -1 if file is not currently open. Example: Find out if the last Employee was accessed by Name (index 0) or Number (index 1). int status,fno; fno = GET_FILE_NUM("EMPLOYEE.DAT"); if (fno != -1) if (btr_files[fno].last_index == 0) printf("Last access was by number"); else printf("Last access was by name"); Notes: You will probably never have to call this function directly. It is used mostly by BXTR to attach position blocks and relevant information to the file name that has been passed to a function. Page 36 BTRV Express Btrieve Error Codes These are the possible values that are returned from library function calls to Btrieve through BSTATUS. For more information about each error code, see your Btrieve manual. 1 INVALID OPERATION 2 I/O ERROR (IS THIS A BTRIEVE FILE?) 3 FILE NOT OPENED 4 KEY NOT FOUND 5 DUPLICATES ERROR 6 INVALID KEY NUMBER 7 DIFFERENT KEY NUMBER 8 INVALID POSITIONING 9 END OF FILE 10 MODIFIABLE ERROR 11 INVALID FILE NAME 12 FILE NOT FOUND 13 CANNOT FIND EXTENSION FILE 14 PRE-OPEN ERROR 15 PRE-IMAGE ERROR 16 EXPANSION ERROR 17 CLOSE ERROR 18 DISK FULL 19 UNRECOVERABLE ERROR 20 RECORD MANAGER NOT ACTIVE 21 KEY BUFFER NOT LONG ENOUGH 22 RECORD BUFFER NOT LONG ENOUGH 23 POSITION BLOCK NOT 128 BYTES 24 PAGE SIZE ERROR 25 CREATE I/O ERROR 26 NUMBER OF KEYS 27 KEY POSITION GREATER THAN RECORD LENGTH 28 RECORD TOO LARGE FOR PAGE SIZE 29 KEY LENGTH ERROR 30 NOT VALID BTRIEVE FILE 31 FILE ALREADY EXTENDED 32 EXTEND I/O ERROR 34 EXTEND NAME ERROR 35 DIRECTORY ERROR 36 TRANSACTION ERROR: USE /T WHEN LOADING 37 OTHER TRANSACTION ALREADY ACTIVE 38 TRANSACTION CONTROL FILE ERROR 39 END/ABORT TRANSACTION ERROR 40 TRANSACTION MAX FILES (MUST BE <12) 41 OPEN/CLOSE DURING TRANSACTION 42 INCOMPLETE ACCELERATED ACCESS 43 INVALID DATA RECORD ADDRESS 44 NULL KEY PATH 45 INCONSISTENT KEY FLAGS 46 ACCESS DENIED 47 MAX OPEN BTRIEVE FILES (USE LARGER /M) 48 INVALID ALTERNATE SEQUENCE DEFINITION 49 KEY TYPE ERROR Page 37 BTRV Express 50 OWNER ALREADY SET 51 INVALID OWNER 52 ERROR WRITING CACHE 53 INVALID INTERFACE (UPGRADE YOUR BTRIEVE) 80 CONFLICT 81 LOCK FULL 82 LOST POSITION 83 READ OUTSIDE TRANSACTION 84 RECORD IN USE 85 FILE IN USE 86 FILE TABLE FULL (USE LARGER /F) 87 HANDLE FULL 88 MODE ERROR 89 NAME ERROR 90 REDIRECTION TABLE FULL 91 SERVER ERROR 92 TRANSACTION FULL 99 DEMO VERSION MUST USE <=24 RECORDS Page 38 BTRV Express General Notes 1) The maximum number of open files is set in the BTRVEXP.C source code file. When you receive the library, this maximum number of files is 10. To change that, you must set the definition for MAX_OPEN_FILES to another number and recompile the library. 2) If you do change the source code for BTRVEXP.C, be sure to use the batch file BOBJS.BAT to recompile for all four memory models. Sample Programs As an example of how to use the library functions, a set of practice files has been included on your disk. The text file "AREACODE.TXT" contains a list of the telephone area codes for the fifty states. The next section of the manual describes how to use the BTRBUILD utility program to create Btrieve data files. Follow the tutorial to create the file "AREACODE.DAT". You can then use the programs "ALOAD.EXE" and "AREPORT.EXE" to load the data file and report on its contents. The source code for the two ".EXE" files has been supplied on your disk. A third file, "ACREATE.C" has been supplied to demonstrate the use of the BCREATE command. To run that program, you must have the alternate collating sequence file "UPPER.ALT" in the current directory or DOS search path. Other files provided show ways to access the records. "AFIND.C" can be compiled to a program that will search the file for a given area code and return its state. "ASTATE.C" will create a program that asks for a state abbreviation and returns all of the area codes in that state. These source code samples should present a good picture of how the function calls interact. Suggestions or Problems If you have suggestions, comments or problems, you may contact: Srebnick Micro Consulting 6 Kelly Road Hamden, Connecticut 06518 (203) 248-6559 If you have a modem and access to Compuserve, you can leave messages at CIS ID#: 74017,3276. ----------------end-of-author's-documentation--------------- Software Library Information: This disk copy provided as a service of The Public (Software) Library We are not the authors of this program, nor are we associated with the author in any way other than as a distributor of the program in accordance with the author's terms of distribution. Please direct shareware payments and specific questions about this program to the author of the program, whose name appears elsewhere in this documentation. If you have trouble getting in touch with the author, we will do whatever we can to help you with your questions. All programs have been tested and do run. To report problems, please use the form that is in the file PROBLEM.DOC on many of our disks or in other written for- mat with screen printouts, if possible. The P(s)L cannot de- bug programs over the telephone. Disks in the P(s)L are updated monthly, so if you did not get this disk directly from the P(s)L, you should be aware that the files in this set may no longer be the current versions. For a copy of the latest monthly software library newsletter and a list of the 1,900+ disks in the library, call or write The Public (Software) Library P.O.Box 35705 - F Houston, TX 77235-5705 (713) 665-7017